NOTE: A more current version of this document may be found at http://www.cdc.noaa.gov/~hoop/xdfopen.shtml.
The xdfopen GrADS command is a supplement to the
sdfopen command.
The sdfopen
command allows access to COARDS-compliant netCDF
/HDF-SDS files, while xdfopen
allows access to some non-compliant netCDF/HDF-SDS
files. The xdfopen
command references a data descriptor file, with syntax very similar to that
which is
used for objects of the open command. The purpose is to make up for
metadata
which is either missing from the SDF file, or not provided in
accordance with the COARDS conventions. Also, one can
specify alternative metadata
as a substitute for existing COARDS-compliant metadata.
The output of the netCDF or HDF ncdump
command is extremely useful in writing this data descriptor file
(DDF). Follow
this link
to see an annotated example of such an ncdump output.
Follow this link
to see an example DDF, based on the above ncdump
output, that is annotated with comment lines.
The only required statement is DSET. With only that, it should devolve into working like sdfopen. In addition to the lines in the example, "ZDEF", "OPTIONS YREV", "OPTIONS ZREV", "OPTIONS TEMPLATE", and "OPTIONS 365_day_calendar" are supported. NOTHING ELSE is at this time. Some of the above are used in the second, more complicated example.
The ?DEF lines have an additional, mixed case, first parameter that names an SDF dimension. Even if the optional second through fifth parameters exist, the dimension name is used to achieve dimension order independence, so it must be real within the SDF. This parameter of the ?DEF lines, and the first parameter of the VARIABLE definition lines, discussed below, are the only parts of the data descriptor file that aren't converted to lower case before they are interpreted. For example, in the data descriptor line:
XDEF dimension1 144 LINEAR 0.0 2.5The string "dimension1" must be a dimension in the SDF, as listed in the first part of the output from ncdump applied to that SDF.
The data variable lines have a somewhat complex-seeming syntax, that becomes easier with practice. The first parameter has the syntax:
{SDFname_in_mixed_case_and_included_blanks=>}grads_abbrev
That is to say, in the absence of "=>", the
grads_abbrev matches the
SDFname, which only works if the SDFname is
15 characters or less in length,
owing to GrADS' ideas about the length of abbrevs. Also,
note that, since
GrADS lower-cases all of the commands you type at the
GrADS prompt, using this
"=>" mechanism is necessary if any part of the
netCDF
variable name is in upper case.
The part after the "=>" (or the entire parameter, if the
"=>"
is absent) should be in lower case, otherwise you will not be able to enter
that name in GrADS commands. The second and third
parameters have the familiar (from DDFs for the open command)
meanings of
#levels and units, while the
remainder of the line is the long name, as before. For example, in the
data descriptor line:Moisture=>moisture 1 99 MoistureThe string "Moisture" matches a variable name in the SDF, while the string "moisture" is used in GrADS commands to reference that same variable. One difference between data descriptor files for xdfopen and those for the open command is that xdfopen doesn't care how Z_dimension-less and Z_dimension-full variables are ordered between VARS and ENDVARS. This is a relaxation over DDFs for the open command.
The following more complicated example comes from a real-world HDF-SDS file from the NASA-Goddard Data Assimilation Office. This is the output from running the HDF version of ncdump on the file, while this is the annotated DDF for the HDF-SDS file. Note that the dimension names in this HDF-SDS file are of the form "XDim:DAOgrid", for example. The colon is part of the name of the dimension, not a part of the syntax of the DDF. Note also the use of the "=>" syntax in the VARIABLE definition lines, owing to the fact the HDF-SDS variable names, for example "TEMPERATURE" are in upper case. The DDF allows the use of lower-case, shorter names in GrADS commands (in this example, "temp"). This example makes use of the "OPTIONS YREV" statement, as the latitudes in this file run from north to south, contrary to the direction assumed by GrADS.
For additional info on GrADS' SDF interface, contact hoop@cdc.noaa.gov.